
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

    <title>Directives Reference &#8212; Leo 6.7.2 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/classic.css" />
    <link rel="stylesheet" type="text/css" href="_static/custom.css" />
    
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    
    <script src="_static/sidebar.js"></script>
    
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Leo and Other Programs" href="leoandotherprograms.html" />
    <link rel="prev" title="Leo’s Commands Reference" href="commands.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="leoandotherprograms.html" title="Leo and Other Programs"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="commands.html" title="Leo’s Commands Reference"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="leo_toc.html">Leo 6.7.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="usersguide.html" accesskey="U">Leo’s Users Guide</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Directives Reference</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="directives-reference">
<h1>Directives Reference<a class="headerlink" href="#directives-reference" title="Permalink to this heading">¶</a></h1>
<div class="contents local topic" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#part-1-file-directives" id="id2">Part 1: &#64;&lt;file&gt; directives</a></p>
<ul>
<li><p><a class="reference internal" href="#asis-path" id="id3">&#64;asis &lt;path&gt;</a></p></li>
<li><p><a class="reference internal" href="#auto-path" id="id4">&#64;auto &lt;path&gt;</a></p>
<ul>
<li><p><a class="reference internal" href="#auto-sanity-checks" id="id5">&#64;auto sanity checks</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#clean-path" id="id6">&#64;clean &lt;path&gt;</a></p></li>
<li><p><a class="reference internal" href="#edit-path" id="id7">&#64;edit &lt;path&gt;</a></p></li>
<li><p><a class="reference internal" href="#file-path-aka-thin" id="id8">&#64;file &lt;path&gt; (aka &#64;thin)</a></p></li>
<li><p><a class="reference internal" href="#nosent-path" id="id9">&#64;nosent &lt;path&gt;</a></p></li>
<li><p><a class="reference internal" href="#shadow-path-deprecated" id="id10">&#64;shadow &lt;path&gt; (deprecated)</a></p></li>
<li><p><a class="reference internal" href="#path-expressions" id="id11">Path expressions</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#part-2-all-and-others" id="id12">Part 2: &#64;all and &#64;others</a></p></li>
<li><p><a class="reference internal" href="#part-3-syntax-coloring-directives" id="id13">Part 3: Syntax coloring directives</a></p></li>
<li><p><a class="reference internal" href="#part-4-dangerous-directives" id="id14">Part 4: Dangerous directives</a></p></li>
<li><p><a class="reference internal" href="#part-5-all-other-directives" id="id15">Part 5: All other directives</a></p></li>
</ul>
</div>
<section id="part-1-file-directives">
<h2><a class="toc-backref" href="#id2">Part 1: &#64;&lt;file&gt; directives</a><a class="headerlink" href="#part-1-file-directives" title="Permalink to this heading">¶</a></h2>
<p id="index-0">This section discusses the &#64;&lt;file&gt; directives. These directives create or import external files.</p>
<p>&#64;&lt;file&gt; nodes create external files:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@asis</span> <span class="o">&lt;</span><span class="n">filename</span><span class="o">&gt;</span>        <span class="n">write</span> <span class="n">only</span><span class="p">,</span> <span class="n">no</span> <span class="n">sentinels</span><span class="p">,</span> <span class="n">exact</span> <span class="n">line</span> <span class="n">endings</span>
<span class="nd">@auto</span> <span class="o">&lt;</span><span class="n">filename</span><span class="o">&gt;</span>        <span class="n">recommended</span>
<span class="nd">@clean</span> <span class="o">&lt;</span><span class="n">filename</span><span class="o">&gt;</span>       <span class="n">recommended</span>
<span class="nd">@edit</span> <span class="o">&lt;</span><span class="n">filename</span><span class="o">&gt;</span>        <span class="nd">@edit</span> <span class="n">node</span> <span class="n">contains</span> <span class="n">entire</span> <span class="n">file</span>
<span class="nd">@file</span> <span class="o">&lt;</span><span class="n">filename</span><span class="o">&gt;</span>        <span class="n">recommended</span>
<span class="nd">@nosent</span> <span class="o">&lt;</span><span class="n">filename</span><span class="o">&gt;</span>      <span class="n">write</span> <span class="n">only</span><span class="p">,</span> <span class="n">no</span> <span class="n">sentinels</span>
</pre></div>
</div>
<p><strong>Note</strong>: &#64;file, &#64;clean and &#64;auto are the recommended ways of creating external files. &#64;asis and &#64;nosent are for special occasions.</p>
<p><strong>Note</strong>: All these directive must appear in headlines.</p>
<p>The following table compares the various ways of creating external files. Later sections provide more details:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>                         Sections &amp;   File data in
@&lt;file&gt; kind  Sentinels?  @others?    .leo file?    Notes
------------  ---------- -----------  ------------  -----
@asis            no         no           yes
@auto            no         yes          no         1, 2
@auto-xx         no         yes          no         1, 2
@clean           no         yes          yes
@edit            no         no           no
@file            yes        yes          no
@nosent          no         yes          yes
</pre></div>
</div>
<p><strong>Note 1</strong>: &#64;auto nodes read files using language-specific importers.
By default, the file’s extension determines the importer:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extensions</span>                  <span class="n">Importer</span>
<span class="o">----------</span>                  <span class="o">--------</span>
<span class="o">.</span><span class="n">c</span><span class="p">,</span> <span class="o">.</span><span class="n">cc</span><span class="p">,</span> <span class="o">.</span><span class="n">c</span><span class="o">++</span><span class="p">,</span> <span class="o">.</span><span class="n">cpp</span><span class="p">,</span><span class="o">.</span><span class="n">cxx</span>    <span class="n">C</span>
<span class="o">.</span><span class="n">cs</span><span class="s1">&#39;, .c#&#39;</span>                  <span class="n">C</span> <span class="n">Sharp</span>
<span class="o">.</span><span class="n">el</span>                         <span class="n">Elisp</span>
<span class="o">.</span><span class="n">h</span><span class="p">,</span> <span class="o">.</span><span class="n">h</span><span class="o">++</span>                    <span class="n">C</span>
<span class="o">.</span><span class="n">html</span><span class="p">,</span> <span class="o">.</span><span class="n">htm</span>                 <span class="n">HTML</span>
<span class="o">.</span><span class="n">ini</span>                        <span class="n">Config</span> <span class="n">file</span>
<span class="o">.</span><span class="n">ipynb</span>                      <span class="n">Jupyter</span> <span class="n">notebook</span>
<span class="o">.</span><span class="n">java</span>                       <span class="n">Java</span>
<span class="o">.</span><span class="n">js</span>                         <span class="n">JavaScript</span>
<span class="o">.</span><span class="n">md</span>                         <span class="n">Markdown</span>
<span class="o">.</span><span class="n">org</span>                        <span class="n">Org</span> <span class="n">Mode</span>
<span class="o">.</span><span class="n">otl</span>                        <span class="n">Vim</span> <span class="n">outline</span>
<span class="o">.</span><span class="n">pas</span>                        <span class="n">Pascal</span>
<span class="o">.</span><span class="n">php</span>                        <span class="n">PHP</span>
<span class="o">.</span><span class="n">py</span><span class="p">,</span> <span class="o">.</span><span class="n">pyi</span><span class="p">,</span> <span class="o">.</span><span class="n">pyw</span>             <span class="n">Python</span>
<span class="o">.</span><span class="n">rest</span><span class="p">,</span> <span class="o">.</span><span class="n">rst</span>                 <span class="n">reStructuredText</span>
<span class="o">.</span><span class="n">ts</span>                         <span class="n">TypeScript</span>
<span class="o">.</span><span class="n">xml</span>                        <span class="n">XML</span>
</pre></div>
</div>
<p><strong>Note 2</strong>: You can also specify importers <em>explicitly</em> as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@auto</span><span class="o">-</span><span class="n">xxx</span>           <span class="n">Importer</span>
<span class="o">---------</span>           <span class="o">--------</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">ctext</span>         <span class="n">ctext</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">markdown</span>      <span class="n">markdown</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">md</span>            <span class="n">markdown</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">org</span>           <span class="n">org</span><span class="o">-</span><span class="n">mode</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">org</span><span class="o">-</span><span class="n">mode</span>      <span class="n">org</span><span class="o">-</span><span class="n">mode</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">otl</span>           <span class="n">vimoutline</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">vim</span><span class="o">-</span><span class="n">outline</span>   <span class="n">vimoutline</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">rst</span>           <span class="n">reStructuredText</span>
</pre></div>
</div>
<p><strong>Important</strong>: The importers/exporters for markdown, org-mode, reStructuredText and vimoutline files automatically generate section heading of the appropriate level. Body text of the top-level &#64;auto node is ignored.</p>
<section id="asis-path">
<h3><a class="toc-backref" href="#id3">&#64;asis &lt;path&gt;</a><a class="headerlink" href="#asis-path" title="Permalink to this heading">¶</a></h3>
<p id="index-1">The &#64;asis directive creates an external file without sentinels and without any expansions.</p>
<p>Use this directive only when you must have complete control over every character of the external file. When writing &#64;asis nodes, writes the body text of all nodes in outline order. Leo writes the body text <em>as is</em>, without recognizing section definitions, without expanding section references, and without treating directives specially in any way. In particular, Leo copies all directives, including &#64; or &#64;c directives, to the external file as text. <strong>Warning</strong>: Because the external file contains no sentinels, &#64;nosent trees can not be updated from changes made outside of Leo. If you want this capability, use &#64;clean instead.</p>
<p id="index-2"><strong>The &#64;&#64; convention</strong>: Within &#64;asis trees only, if a headline starts with &#64;&#64;, Leo writes everything in the headline following the &#64;&#64; just before the corresponding body text.</p>
<p>Files created from &#64;asis trees contain <em>nothing</em> not contained in body text (or
&#64;&#64; headlines). In particular, if body text does not end in a newline, the first
line from the next node will concatenated to the last line of the preceding node.</p>
<p>Within &#64;asis trees, Leo writes no sentinels to the external file, so Leo can not update the outline using changes to the external file. When reading .leo files, Leo does <em>not</em> read external files created from &#64;asis nodes. Instead, all data in an &#64;asis tree is stored in the .leo file.</p>
<p>Within &#64;asis trees, Leo recognizes the &#64;ignore directive only in the <em>ancestors</em> of &#64;asis nodes. This allows you to use the &#64;ignore directive to prevent Leo from writing &#64;asis trees.</p>
<p><strong>Note</strong>: &#64;file-asis and &#64;silent are deprecated synonyms for &#64;asis.</p>
</section>
<section id="auto-path">
<h3><a class="toc-backref" href="#id4">&#64;auto &lt;path&gt;</a><a class="headerlink" href="#auto-path" title="Permalink to this heading">¶</a></h3>
<p id="index-3">The &#64;auto directive imports an external file into a tree of nodes.</p>
<p>&#64;auto trees allow people to use Leo in collaborative environments without using sentinels in external files. Even without sentinels, &#64;auto trees can change when the corresponding external file changes outside of Leo.</p>
<p id="index-4">&#64;auto nodes read files using language-specific importers.
By default, the file’s extension determines the importer:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extensions</span>                  <span class="n">Importer</span>
<span class="o">----------</span>                  <span class="o">--------</span>
<span class="o">.</span><span class="n">c</span><span class="p">,</span> <span class="o">.</span><span class="n">cc</span><span class="p">,</span> <span class="o">.</span><span class="n">c</span><span class="o">++</span><span class="p">,</span> <span class="o">.</span><span class="n">cpp</span><span class="p">,</span><span class="o">.</span><span class="n">cxx</span>    <span class="n">C</span>
<span class="o">.</span><span class="n">cs</span><span class="s1">&#39;, .c#&#39;</span>                  <span class="n">C</span> <span class="n">Sharp</span>
<span class="o">.</span><span class="n">el</span>                         <span class="n">Elisp</span>
<span class="o">.</span><span class="n">h</span><span class="p">,</span> <span class="o">.</span><span class="n">h</span><span class="o">++</span>                    <span class="n">C</span>
<span class="o">.</span><span class="n">html</span><span class="p">,</span> <span class="o">.</span><span class="n">htm</span>                 <span class="n">HTML</span>
<span class="o">.</span><span class="n">ini</span>                        <span class="n">Config</span> <span class="n">file</span>
<span class="o">.</span><span class="n">ipynb</span>                      <span class="n">Jupyter</span> <span class="n">notebook</span>
<span class="o">.</span><span class="n">java</span>                       <span class="n">Java</span>
<span class="o">.</span><span class="n">js</span>                         <span class="n">JavaScript</span>
<span class="o">.</span><span class="n">md</span>                         <span class="n">Markdown</span>
<span class="o">.</span><span class="n">org</span>                        <span class="n">Org</span> <span class="n">Mode</span>
<span class="o">.</span><span class="n">otl</span>                        <span class="n">Vim</span> <span class="n">outline</span>
<span class="o">.</span><span class="n">pas</span>                        <span class="n">Pascal</span>
<span class="o">.</span><span class="n">php</span>                        <span class="n">PHP</span>
<span class="o">.</span><span class="n">py</span><span class="p">,</span> <span class="o">.</span><span class="n">pyi</span><span class="p">,</span> <span class="o">.</span><span class="n">pyw</span>             <span class="n">Python</span>
<span class="o">.</span><span class="n">rest</span><span class="p">,</span> <span class="o">.</span><span class="n">rst</span>                 <span class="n">reStructuredText</span>
<span class="o">.</span><span class="n">ts</span>                         <span class="n">TypeScript</span>
<span class="o">.</span><span class="n">xml</span>                        <span class="n">XML</span>
</pre></div>
</div>
<p>You can also specify importers <em>explicitly</em> as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@auto</span><span class="o">-</span><span class="n">xxx</span>           <span class="n">Importer</span>            <span class="n">Notes</span>
<span class="o">---------</span>           <span class="o">--------</span>            <span class="o">-----</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">ctext</span>         <span class="n">ctext</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">markdown</span>      <span class="n">markdown</span>            <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">md</span>            <span class="n">markdown</span>            <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">org</span>           <span class="n">org</span><span class="o">-</span><span class="n">mode</span>            <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">org</span><span class="o">-</span><span class="n">mode</span>      <span class="n">org</span><span class="o">-</span><span class="n">mode</span>            <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">otl</span>           <span class="n">vimoutline</span>          <span class="mi">1</span><span class="p">,</span> <span class="mi">4</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">vim</span><span class="o">-</span><span class="n">outline</span>   <span class="n">vimoutline</span>          <span class="mi">1</span><span class="p">,</span> <span class="mi">4</span>
<span class="nd">@auto</span><span class="o">-</span><span class="n">rst</span>           <span class="n">reStructuredText</span>    <span class="mi">1</span><span class="p">,</span> <span class="mi">5</span>
</pre></div>
</div>
<p><strong>Note 1</strong>: The importers/exporters for markdown, org-mode, reStructuredText and vimoutline files automatically generate section heading of the appropriate level. Body text of the top-level &#64;auto node is ignored.</p>
<p><strong>Note 2</strong>: See the official <a class="reference external" href="http://en.wikipedia.org/wiki/Markdown">Markdown</a> documentation.</p>
<p><strong>Note 3</strong>: See Leo’s <a class="reference external" href="emacs.html#using-org-mode-org-files-in-leo">Emacs</a> documentation and Emacs’s <a class="reference external" href="http://en.wikipedia.org/wiki/Org-mode">org-mode</a> documentation.</p>
<p><strong>Note 4</strong>: See Leo’s <a class="reference external" href="vimBindings.html#using-vimoutline-otl-files-in-leo">vim</a> documentation and Vim’s <a class="reference external" href="http://www.vim.org/scripts/script.php?script_id=3515">vim outline</a> documentation.</p>
<p><strong>Note 5</strong>: See the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> documentation.</p>
<section id="auto-sanity-checks">
<h4><a class="toc-backref" href="#id5">&#64;auto sanity checks</a><a class="headerlink" href="#auto-sanity-checks" title="Permalink to this heading">¶</a></h4>
<p>When importing files into &#64;auto trees, Leo performs several checks to ensure that writing the imported file will produce exactly the same file. These checks can produces <strong>errors</strong> or <strong>warnings</strong>. Errors indicate a potentially serious problem. Leo inserts an &#64;ignore directive in the &#64;auto tree if any error is found. This prevents the &#64;auto tree from modifying the external file.</p>
<p id="index-5">Before importing a file, Leo <strong>regularizes</strong> the leading whitespace of all lines of the original source file. That is, Leo converts blanks to tabs or tabs to blanks depending on the value of the &#64;tabwidth directive in effect for the &#64;auto node. Leo also checks that the indentation of any non-blank line is a multiple of the indentation specified by the &#64;tabwidth directive. <strong>Strict languages</strong> are languages such as Python for which leading whitespace must be preserved exactly as it appears in the original source file. Problems during regularizing whitespace generate errors for strict languages and warnings for non-strict languages.</p>
<p>After importing a file, Leo verifies that writing the &#64;auto node would create the same file as the original file. Such file comparison mismatches generate errors unless the problem involves only leading whitespace for non-strict languages. Whenever a mismatch occurs the first non-matching line is printed.</p>
<p>File comparison mismatches can arise for several reasons:</p>
<ol class="arabic simple">
<li><p>Bugs in the import parsers. Please report any such bugs immediately.</p></li>
<li><p>Underindented lines in classes, methods or function.</p></li>
</ol>
<p id="index-6">An <strong>underindented line</strong> is a line of body text that is indented less then the starting line of the class, method or function in which it appears. Leo outlines can not represent such lines exactly: every line in an external file will have at least the indentation of any unindented line of the corresponding node in the outline. Leo will issue a warning (not an error) for underindented Python comment lines. Such lines can not change the meaning of Python programs.</p>
</section>
</section>
<section id="clean-path">
<h3><a class="toc-backref" href="#id6">&#64;clean &lt;path&gt;</a><a class="headerlink" href="#clean-path" title="Permalink to this heading">¶</a></h3>
<p id="index-7">The &#64;clean &lt;filename&gt; creates an external file without sentinel lines.
&#64;clean trees will probably be the most convenient way of creating and
accessing external files for most people.</p>
<p>When writing an &#64;clean tree, Leo expands section references, &#64;all and</p>
<p>When reading an &#64;clean tree, Leo propagates changes from the external file
to the &#64;clean tree using the <a class="reference external" href="appendices.html#the-mulder-ream-update-algorithm">Mulder/Ream update algorithm</a>.</p>
<p><strong>Note</strong>: The &#64;bool force_newlines_in_at_nosent_bodies setting controls whether
Leo writes a trailing newline if non-empty body text does not end in a newline.
The default is True.</p>
<p><strong>Note</strong>: The <a class="reference external" href="commands.html#syncing-clean-files">check-nodes</a> command helps sync &#64;clean trees when
collaborating with others.</p>
</section>
<section id="edit-path">
<h3><a class="toc-backref" href="#id7">&#64;edit &lt;path&gt;</a><a class="headerlink" href="#edit-path" title="Permalink to this heading">¶</a></h3>
<p id="index-8">The &#64;edit directive imports an external file into a single node.</p>
<p>When reading &#64;edit nodes, Leo reads the entire file into the &#64;edit node. Lines
that look like sentinels will be read just as they are.</p>
<p>When writing &#64;edit nodes, &#64;edit nodes must not have children and section
references and &#64;others are not allowed.</p>
</section>
<section id="file-path-aka-thin">
<h3><a class="toc-backref" href="#id8">&#64;file &lt;path&gt; (aka &#64;thin)</a><a class="headerlink" href="#file-path-aka-thin" title="Permalink to this heading">¶</a></h3>
<p id="index-9">The &#64;file directive creates an external file containing sentinels. When writing
&#64;file trees, Leo expands section references and &#64;all and &#64;others directives.</p>
<p>When reading external files created by &#64;file, the sentinels allow Leo to
recreate all aspects of the outline. In particular, Leo can update the
outline based on changes made to the file by another editor.</p>
<p><strong>Important</strong>: &#64;file is the recommended way to create and edit most
files. In particular, using &#64;file nodes is <strong>highly recommended</strong>
when sharing external files in a collaborative environment. The &#64;all
directivive is designed for “catch-all” files, like todo.txt or
notes.txt or whatever. Such files are assumed to contain a random
collection of nodes, so there is no language in effect and no real
comment delimiters.</p>
<p>The &#64;thin directive is a synonym for &#64;file.</p>
<p>Prior to Leo 4.7, &#64;file worked differently from &#64;thin. This should not be
a problem: Leo 4.7 can read all external files written by Leo 4.6.</p>
</section>
<section id="nosent-path">
<h3><a class="toc-backref" href="#id9">&#64;nosent &lt;path&gt;</a><a class="headerlink" href="#nosent-path" title="Permalink to this heading">¶</a></h3>
<p id="index-10">The &#64;nosent directive creates an external file <strong>without</strong> sentinels. When writing
&#64;nosent trees, Leo expands section references and &#64;all and &#64;others directives. <strong>Warning</strong>: Because the external file contains no sentinels, &#64;nosent trees can not be updated from changes made outside of Leo. If you want this capability, use &#64;clean instead.</p>
</section>
<section id="shadow-path-deprecated">
<h3><a class="toc-backref" href="#id10">&#64;shadow &lt;path&gt; (deprecated)</a><a class="headerlink" href="#shadow-path-deprecated" title="Permalink to this heading">¶</a></h3>
<p id="index-11"><strong>Important</strong>: As of Leo 5.1, &#64;shadow is <strong>deprecated</strong> Use &#64;clean instead. &#64;clean is faster than &#64;shadow and requires no hidden files.</p>
<p>The &#64;shadow directive creates <em>two</em> external files, a <strong>public</strong> file without sentinels, and a <strong>private</strong> file containing sentinels.</p>
<p>When reading an &#64;shadow node, Leo uses the <a class="reference external" href="appendices.html#the-mulder-ream-update-algorithm">Mulder/Ream update algorithm</a> to compare the public and private files, then updates the outline based on changes to the <em>public</em> file.</p>
<p>Leo can do an initial import of &#64;shadow trees by parsing the corresponding public file, exactly as is done for &#64;auto nodes.</p>
</section>
<section id="path-expressions">
<h3><a class="toc-backref" href="#id11">Path expressions</a><a class="headerlink" href="#path-expressions" title="Permalink to this heading">¶</a></h3>
<p>Within &#64;path and &#64;&lt;file&gt; paths, Leo evaluates <code class="docutils literal notranslate"><span class="pre">{{exp}}</span></code> with the the following symbols defined: <code class="docutils literal notranslate"><span class="pre">c</span></code>, <code class="docutils literal notranslate"><span class="pre">g</span></code>, <code class="docutils literal notranslate"><span class="pre">p</span></code>, <code class="docutils literal notranslate"><span class="pre">os</span></code> and <code class="docutils literal notranslate"><span class="pre">sys</span></code>. Also, <code class="docutils literal notranslate"><span class="pre">sep</span></code> is defined as os.sep.
File names are relative to the directory containing the .leo file, but that can be overridden, depending on the form of the file name. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@file</span> <span class="p">{{</span><span class="n">c</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">getString</span><span class="p">(</span><span class="s1">&#39;my-dir&#39;</span><span class="p">)}}{{</span><span class="n">sep</span><span class="p">}}</span><span class="n">myFile</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
</section>
</section>
<section id="part-2-all-and-others">
<h2><a class="toc-backref" href="#id12">Part 2: &#64;all and &#64;others</a><a class="headerlink" href="#part-2-all-and-others" title="Permalink to this heading">¶</a></h2>
<p>These control how Leo places text when writing external files. They are two of the most important directives in Leo.</p>
<dl class="glossary simple">
</dl>
<p id="index-12">&#64;all</p>
<blockquote>
<div><p>Copies <em>all</em> descendant nodes to the external file. Use &#64;all to place
unrelated data in an external file.</p>
<p>The &#64;all directive is valid only in the body of &#64;file trees.</p>
<p>Within the range of an &#64;all directive, Leo ignores the &#64;others directive
and section references, so Leo will not complain about orphan nodes.</p>
<p>The &#64;all directivive is designed for “catch-all” files, like
todo.txt or notes.txt or whatever. Such files are assumed to
contain a random collection of nodes, so there is no language in
effect and no real comment delimiters.</p>
</div></blockquote>
<p id="index-13">&#64;others</p>
<blockquote>
<div><p>Writes the body text of all unnamed descendant into the external file, in
outline order.</p>
<p>Whitespace appearing before &#64;others directive adds to the indentation of
all nodes added by the &#64;others directive.</p>
<p>A single node may contain only one &#64;others directive, but descendant nodes
may have other &#64;others directives.</p>
</div></blockquote>
</section>
<section id="part-3-syntax-coloring-directives">
<h2><a class="toc-backref" href="#id13">Part 3: Syntax coloring directives</a><a class="headerlink" href="#part-3-syntax-coloring-directives" title="Permalink to this heading">¶</a></h2>
<p>The &#64;color, &#64;killcolor, &#64;nocolor and &#64;nocolor-node directives control how
Leo colors text in the body pane.</p>
<p id="index-14">These directives typically affect the node in which they appear and all descendant nodes. Exception: an <strong>ambiguous node</strong>, a node containing both &#64;color and &#64;nocolor directives, has no effect on how Leo colors text in descendant nodes.</p>
<dl class="glossary simple">
</dl>
<p id="index-15">&#64;color</p>
<blockquote>
<div><p>Enables syntax coloring until the next &#64;nocolor directive.</p>
</div></blockquote>
<p id="index-16">&#64;killcolor</p>
<blockquote>
<div><p>Disables syntax coloring in a node, overriding all &#64;color, &#64;nocolor or
&#64;nocolor-node directives in the same node.</p>
</div></blockquote>
<p id="index-17">&#64;nocolor</p>
<blockquote>
<div><p>Disables syntax coloring until the next &#64;nocolor directive.</p>
</div></blockquote>
<p id="index-18">&#64;nocolor-node</p>
<blockquote>
<div><p>Disables coloring for only the node containing it. The &#64;nocolor-node
directive overrides the &#64;color and &#64;nocolor directives within the same
node.</p>
</div></blockquote>
</section>
<section id="part-4-dangerous-directives">
<h2><a class="toc-backref" href="#id14">Part 4: Dangerous directives</a><a class="headerlink" href="#part-4-dangerous-directives" title="Permalink to this heading">¶</a></h2>
<p>These directives alter how Leo represents data in external files. They are <strong>dangerous</strong>–mistakes in using these sentinels can make it impossible for Leo to read the resulting external file. Use them with care!</p>
<p>Nevertheless, these sentinels can be useful in special situations.</p>
<dl class="glossary simple">
</dl>
<p id="index-19">&#64;comment &lt;1, 2 or three comment delims&gt;</p>
<blockquote>
<div><p>Sets the comment delimiters in &#64;file and &#64;shadow files.
<strong>Important</strong>: Use &#64;comment for unusual situations only. In most cases, you
should use the &#64;language directive to set comment delimiters.</p>
<p>The &#64;comment directive may be followed by one, two or three delimiters,
separated by whitespace. If one delimiter is given, it sets the delimiter
used by single-line comments. If two delimiters are given, they set the
block comment delimiter. If three delimiters are given, the first sets the
single-line-comment delimiter, and the others set the block-comment
delimiters.</p>
<p>Within these delimiters, underscores represent a significant space, and
double underscores represent a newline. Examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@comment</span> <span class="n">REM_</span>
<span class="nd">@comment</span> <span class="n">__</span><span class="o">=</span><span class="n">pod__</span> <span class="n">__</span><span class="o">=</span><span class="n">cut__</span>
</pre></div>
</div>
<p>The second line sets PerlPod comment delimiters.</p>
<p><strong>Warning</strong>: the &#64;comment and &#64;delims directives <strong>must not</strong> appear in
the same node. Doing so may create a file that Leo can not read.</p>
<p><strong>Note</strong>: &#64;language and &#64;comment may appear in the same node, provided
that &#64;comment appears <em>after</em> the &#64;language directive: &#64;comment overrides
&#64;language.</p>
<p>The &#64;comment directive must precede the first section name or &#64;c
directive.</p>
<p>There are situations where using &#64;delims or &#64;comment is not avoidable or impractical to
add new language definition, and including it causes the resulting file to be invalid.
In place of delimiter definition, use &#64;0x + delimiter encoded in hexadecimal.
The hexadecimal part must be acceptable input to binascii.unhexlify(), otherwise whole
directive will be ignored. Use binascii.hexlify(‘my-delimiter’) to generate it.
Decoded delimiters are not checked for validity (such as, UTF-8) and whether they
do not clash with Leo format (like newline or NUL characters)!</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@comment</span> <span class="o">@</span><span class="mh">0x3c212d2d2120</span> <span class="o">@</span><span class="mh">0x202d2d3e</span>
</pre></div>
</div>
<p>for GenshiXML is the same definition as</p>
<blockquote>
<div><p>&#64;comment &lt;!–!_ _–&gt;</p>
</div></blockquote>
<p>to create comments that will be removed from the output by Genshi. But the latter would
cause XML parsing error on the &#64;comment line.</p>
</div></blockquote>
<p id="index-20">&#64;delims &lt;1 or 2 comment delims&gt;</p>
<blockquote>
<div><p>Sets comment delimiters in external files containing sentinel lines.</p>
<p>The &#64;delims directive requires one or two delimiters, separated by
whitespace. If one delimiter is present it sets the single-line-comment
delimiter. If two delimiters are present they set block comment delimiters.</p>
<p>This directive is often used to place Javascript text inside XML or HTML
files. Like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@delims</span> <span class="o">/*</span> <span class="o">*/</span>
<span class="n">Javascript</span> <span class="n">stuff</span>
<span class="nd">@delims</span> <span class="o">&lt;--</span> <span class="o">--&gt;</span>
<span class="n">HTML</span> <span class="n">stuff</span>
</pre></div>
</div>
<p><strong>Warning</strong>: you <strong>must</strong> change back to previous delimiters using another
&#64;delims directive. Failure to change back to the previous delimiters will
thoroughly corrupt the external file as far as compilers, HTML renderers,
etc. are concerned. Leo does not do this automatically at the end of a node.</p>
<p><strong>Warning</strong>: the &#64;comment and &#64;delims directives <strong>must not</strong> appear in
the same node. Doing so may create a file that Leo can not read.</p>
<p><strong>Note</strong>: The &#64;delims directive can not be used to change the comment
strings at the start of the external file, that is, the comment strings for
the &#64;+leo sentinel and the initial &#64;+body and &#64;+node sentinels.</p>
</div></blockquote>
</section>
<section id="part-5-all-other-directives">
<h2><a class="toc-backref" href="#id15">Part 5: All other directives</a><a class="headerlink" href="#part-5-all-other-directives" title="Permalink to this heading">¶</a></h2>
<p>This section is a reference guide for all other Leo directives, organized alphabetically.</p>
<p>Unless otherwise noted, all directives listed are valid only in body text, and they must start at the leftmost column of the node.</p>
<dl class="glossary simple">
</dl>
<span class="target" id="index-21"></span><span class="target" id="index-22"></span><p id="index-23">&#64; and &#64;doc</p>
<blockquote>
<div><p>These directives start a doc part. &#64;doc is a synonym for &#64;. Doc parts
continue until an &#64;c directive or the end of the body text. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">@</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">comment</span> <span class="ow">in</span> <span class="n">a</span> <span class="n">doc</span> <span class="n">part</span><span class="o">.</span>
<span class="n">Doc</span> <span class="n">parts</span> <span class="n">can</span> <span class="n">span</span> <span class="n">multiple</span> <span class="n">lines</span><span class="o">.</span>
<span class="n">The</span> <span class="nb">next</span> <span class="n">line</span> <span class="n">ends</span> <span class="n">the</span> <span class="n">doc</span> <span class="n">part</span>
<span class="nd">@c</span>
</pre></div>
</div>
<p>When writing external files, Leo writes doc parts as comments.</p>
<p>Leo does not recognize &#64; or &#64;doc in &#64;asis trees or when the &#64;all or
&#64;delims directives are in effect.</p>
</div></blockquote>
<span class="target" id="index-24"></span><p id="index-25">&#64;c and &#64;code</p>
<blockquote>
<div><p>Ends any doc part and starts a code part.</p>
<p>&#64;code is a deprecated synonym for &#64;c.</p>
<p>Leo does not recognize this directive in &#64;asis trees.</p>
</div></blockquote>
<p>&#64;chapter</p>
<blockquote>
<div><p>An &#64;chapter tree represents a chapter. For full details, see <a class="reference external" href="commands.html#using-chapters">Using Chapters</a>.</p>
<p>These directives must appear in the node’s headline.</p>
</div></blockquote>
<p id="index-27">&#64;encoding &lt;encoding&gt;</p>
<blockquote>
<div><p>Specifies the Unicode encoding for an external file. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@encoding</span> <span class="n">iso</span><span class="o">-</span><span class="mi">8859</span><span class="o">-</span><span class="mi">1</span>
</pre></div>
</div>
<p>When reading external files, the encoding given must match the encoding
actually used in the external file or “byte hash” will result.</p>
</div></blockquote>
<p id="index-28">&#64;first &lt;text&gt;</p>
<blockquote>
<div><p>Places lines at the very start of an external file, before any Leo
sentinels. &#64;first lines must be the <em>very first</em> lines in an &#64;&lt;file&gt; node.
More then one &#64;first lines may appear.</p>
<p>This creates two first lines, a shebang line and a Python encoding line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@first</span> <span class="c1">#! /usr/bin/env python</span>
<span class="nd">@first</span> <span class="c1"># -*- coding: utf-8 -*-</span>
</pre></div>
</div>
<p>Here is a perl example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@first</span> <span class="c1">#!/bin/sh -- # perl, to stop looping</span>
<span class="nd">@first</span> <span class="nb">eval</span> <span class="s1">&#39;exec /usr/bin/perl -w -S $0 ${1+&quot;$@&quot;}&#39;</span>
<span class="nd">@first</span>     <span class="k">if</span> <span class="mi">0</span><span class="p">;</span>
</pre></div>
</div>
</div></blockquote>
<p>&#64;ignore</p>
<blockquote>
<div><p>Tells Leo to ignore the subtree in which it appears.</p>
<p>In the body text of most top-level &#64;&lt;file&gt; nodes, the &#64;ignore directive
causes Leo not to write the tree. However, Leo ignores &#64;ignore directives
in &#64;asis trees.</p>
<p>Plugins and other parts of Leo sometimes &#64;ignore for their own purposes. For
example, Leo’s unit testing commands will ignore trees containing &#64;ignore.
In such cases, the &#64;ignore directive may appear in the headline or body
text.</p>
</div></blockquote>
<span class="target" id="index-29"></span><p>&#64;language &lt;language name&gt;</p>
<blockquote>
<div><p>Specifies the language in effect, including comment delimiters.
If no &#64;language directive is in effect, Leo uses the defaults specified
by the &#64;string target-language setting.</p>
<p>A node may contain multiple &#64;language directives.</p>
<p>The valid language names include the following: actionscript, ada95, ahk, antlr, apacheconf, apdl, applescript, asciidoc, asp, aspect_j, assembly_macro32, assembly_mcs51, assembly_parrot, assembly_r2000, assembly_x86, awk, b, batch, bbj, bcel, bibtex, c, chill, clojure, cobol, coldfusion, cplusplus, csharp, css, cython, d, dart, doxygen, eiffel, embperl, erlang, factor, forth, fortran, fortran90, foxpro, gettext, groovy, haskell, haxe, html, i4gl, icon, idl, inform, ini, inno_setup, interlist, io, java, javascript, jhtml, jmk, jsp, kivy, latex, lilypond, lisp, lotos, lua, mail, makefile, maple, matlab, md, ml, modula3, moin, mqsc, netrexx, nqc, nsi, nsis2, objective_c, objectrexx, occam, omnimark, pascal, patch, perl, php, phpsection, pike, pl1, plain, plsql, pop11, postscript, povray, powerdynamo, prolog, pseudoplain, psp, ptl, pvwave, pyrex, python, r, rebol, redcode, rest, rhtml, rib, rpmspec, rtf, ruby, rview, sas, scala, scheme, sdl_pr, sgml, shell, shellscript, shtml, smalltalk, smi_mib, splus, sqr, squidconf, ssharp, swig, tcl, tex, texinfo, text, tpl, tsql, uscript, vbscript, velocity, verilog, vhdl, xml, xsl, yaml, zpt.</p>
<p><strong>Note</strong>: Shell files have comments that start with #.</p>
<p>Case is ignored in the language names. For example, the following are
equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@language</span> <span class="n">html</span>
<span class="nd">@language</span> <span class="n">HTML</span>
</pre></div>
</div>
<p>The &#64;language directive also controls syntax coloring. For language x, the
file leo/modes/x.py describes how to colorize the language. To see the
languages presently supported, look in the leo/modes directory. There are
over 100 such languages.</p>
</div></blockquote>
<p id="index-30">&#64;last &lt;text&gt;</p>
<blockquote>
<div><p>Places lines at the very end of external files.</p>
<p>This directive must occur at the <em>very end</em> of top-level &#64;&lt;file&gt; nodes. More
than one &#64;last directive may exist. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>@first &lt;?php
...
@last ?&gt;
</pre></div>
</div>
<p>Leo does not recognize &#64;last directive in &#64;asis trees.</p>
</div></blockquote>
<p id="index-31">&#64;lineending cr/lf/nl/crlf</p>
<blockquote>
<div><p>Sets the line endings for external files.
This directive overrides the &#64;string output_newline setting.</p>
<p>The valid forms of the &#64;lineending directive are:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 31%" />
<col style="width: 69%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p>&#64;lineending nl</p></td>
<td><p>The default, Linux.</p></td>
</tr>
<tr class="row-even"><td><p>&#64;lineending cr</p></td>
<td><p>Mac</p></td>
</tr>
<tr class="row-odd"><td><p>&#64;lineending crlf</p></td>
<td><p>Windows</p></td>
</tr>
<tr class="row-even"><td><p>&#64;lineending lf</p></td>
<td><p>Same as ‘nl’, not recommended</p></td>
</tr>
<tr class="row-odd"><td><p>&#64;lineending platform</p></td>
<td><p>Same as platform value for output_newline setting.</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p id="index-32">&#64;nowrap</p>
<blockquote>
<div><p>Disables line wrapping the Leo’s body pane.</p>
<p>Only the first &#64;wrap or &#64;nowrap directive in a node has any effect.</p>
<p>&#64;nowrap may appear in either headlines or body text.</p>
</div></blockquote>
<p id="index-33">&#64;pagewidth &lt;n&gt;</p>
<blockquote>
<div><blockquote>
<div><p>Sets the page width used by the reformat-paragraph command.
This directive also controls how &#64;doc parts are broken into lines.
&lt;n&gt; should be a positive integer.  For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@pagewidth</span> <span class="mi">100</span>
</pre></div>
</div>
</div></blockquote>
<p>The &#64;pagewidth directive overrides the &#64;int page_width setting.</p>
</div></blockquote>
<span class="target" id="index-34"></span><span class="target" id="index-35"></span><p id="index-36">&#64;path &lt;path&gt;</p>
<blockquote>
<div><p>Sets the <strong>path prefix</strong> for relative filenames for all &#64;&lt;file&gt; tree.</p>
<p>This directive may appear in headlines or body text, and may
appear in top-level &#64;&lt;file&gt; nodes <em>except</em> &#64;file nodes.</p>
<p>The path is an <strong>absolute path</strong> if it begins with c:\ or /,
otherwise the path is a <strong>relative</strong> paths.</p>
<p>Multiple &#64;path directives may contribute to the path prefix.
Absolute paths overrides any ancestor &#64;path directives.
Relative paths add to the path prefix.</p>
<p>If no &#64;path directives are in effect, the default path prefix is
the directory containing the .leo file.</p>
</div></blockquote>
<p id="index-37">&#64;persistence</p>
<p>With &#64;clean and &#64;file, Leo can store <strong>persistent data</strong> in nodes. This information consists of the node’s <strong>gnx</strong> (Global Node Index) and the node’s <strong>uA</strong>, (User Attributes). The gnx gives each node a unique, immutable identity. Gnx’s make clones possible. The uA allows scripts and plugins to associate arbitrarily much additional data with each node.</p>
<p>By default, Leo’s importers preserve neither gnx’s nor uA’s. This makes imported &#64;auto trees second class citizens. To remedy this, if an outline contains an &#64;persistence node, Leo will save data in the &#64;persistence tree that allows Leo to recover gnx’s and uA’s when re-reading &#64;auto files later. This allows clone links and uA’s to persist.</p>
<p>&#64;persistence is an optional feature. The stored data is akin to bookmarks. The data can “break” (become inaccessible) if the structure (including class/method/function names) changes. However, the data will typically break infrequently. To disable this feature, just delete an existing &#64;persistence node or change &#64;persistence to &#64;&#64;persistence.</p>
<span class="target" id="index-38"></span><p id="index-39">&#64;tabwidth &lt;n&gt;</p>
<blockquote>
<div><p>Sets the width of tabs.
Negative tab widths cause Leo to convert tabs to spaces.</p>
</div></blockquote>
<p id="index-40">&#64;wrap</p>
<blockquote>
<div><p>Enables line wrapping in Leo’s body pane.</p>
<p>Only the first &#64;wrap or &#64;nowrap directive in a node has any effect.</p>
<p>&#64;wrap may appear in either headlines or body text.</p>
</div></blockquote>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="leo_toc.html">
              <img class="logo" src="_static/LeoLogo.svg" alt="Logo"/>
            </a></p>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="commands.html"
                          title="previous chapter">Leo’s Commands Reference</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="leoandotherprograms.html"
                          title="next chapter">Leo and Other Programs</a></p>
  </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>

      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="leoandotherprograms.html" title="Leo and Other Programs"
             >next</a> |</li>
        <li class="right" >
          <a href="commands.html" title="Leo’s Commands Reference"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="leo_toc.html">Leo 6.7.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="usersguide.html" >Leo’s Users Guide</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Directives Reference</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 1997-2023, Edward K. Ream.
      Last updated on February 28, 2023.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
    </div>
  </body>
</html>